HOWTO: Have Fun with ee9, Version 3 
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Admonition 

First of all, make sure you have read, understood and inwardly digested the contents of the README file for this release 
of ee9. Secondly, do the same for‘Users Guide for ee9 .pdfI know, I know! Reading documentation is no 
fun! But it is good for you. You’ll get no pudding until you’ve eaten your greens! 

If that has not put you off the notion entirely, here is some guidance as to how best to use ee9 with Usercode 
programs. Whetstone Algol programs and the EE Time Sharing Director. To be honest, and despite the foregoing, you 
can get a much quicker start by reading ‘Getting started’ and ‘Simple Examples’ in the README file. 

Using Usercode 

The EE KDF9 Usercode manual is the indispensable guide to KDF9 assembly-level programming. It is available in 
DjVu format at: 

http://www.findlavw.plus.com/KDF9/Documents/Usercode%20Manual.divu 

In the olden days, Usercode programs were compiled to machine code using one of KDF9’s native assemblers. 
Unfortunately neither a binary nor a source text of these programs has survived in a usable form. Instead, we have 
David Holdsworth’s brand-new Usercode assembler kal3. It runs on your own computer, generating a KDF9 machine 
code file that ee9 can load and run. 

A selection of mostly small programs can be found in the directory Testing/Assembly. 

I provide some shell commands, in the Testing directory, to make it a little easier to compile and run Usercode. 
These take Usercode programs from text files named with the ‘ .k3’ suffix, make listings in files named with the 
‘. txt’ suffix, and generate KDF9 machine code programs in files named without a suffix. The suffix is optional in a 
name given as a parameter to the ucc, nine and lud commands: if supplied, it must be correct; if omitted, it is 
automatically restored. (With a view to running programs under a Director, it is conventional to give them names that 
eschew lower-case letters.) 

• The ucc (‘Usercode compile’) command runs kal3, saves a compilation listing, and names the KDF9 
machine code file after the input file; e.g.: 

./ucc MY_PROG 

compiles the program in the file Testing/Assembly/MY_PROG. k3, leaving a listing in 
Testing/Assembly/MY_PROG-listing. txt, and a binary in Testing/Binary/MY_PROG, 
conveniently placed for the nine command. 

• The nine command runs a KDF9 machine code program in Testing/Binary; e.g.: 

./nine MY_PROG my_data t 

runs the binary Testing/Binary/MY_PROG, in trace mode (or f, p, x, or nothing at all instead of t), having 
copied the data file Testing/Assembly/my_data. txt to the paper tape reader TR1. 

The tracing verbosity can specified by a fourth parameter, composed of the same characters as the V option in a 
settings file. For example: 

./nine MY_PROG my_data t hps 

runs MY_PROG in trace mode, the tracing verbosity being reduced by omitting the histogram, peripheral I/O 
trace, and signature. If either the TPO or the LPO file is found to be non-empty at the end of a run, it is displayed 
on the terminal. The data file and the diagnostic mode are both optional. To give a mode, but not an input file, 
specify the file parameter as a minus sign; e.g.: 

./nine MY_PROG - f 

• The crine command runs a KDF9 machine code program having attached the card reader CRO to the data 
file, but in every other way the same as the nine command. 

• The nine_test command runs a KDF9 machine code program in test program mode, but in every other 
way the same as the nine command. 
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YOU PROBABLY DON’T NEED TO KNOW THIS: 


• The lud (‘link Usercode data’) command is used by nine to copy a data file into TR1. You can invoke it 
directly to supply a data file in TR1 for a run of ee9 that you call yourself. For example, the following is 
somewhat like the first . /nine command, above: 

./lud my_data 

./ee9 -sp -dt +Binary/MY_PROG 

Walking with Walgol (the Whetstone Algol 60 system) 

With the best will in the world it is impossible to describe the execution of an Algol program, using Walgol, as a ‘run’; 
even ‘walking’ suggests a celerity that was foreign to its nature. Perhaps ‘crawl’ conveys the best impression, but ee9 
runs code so much faster than the KDF9 hardware that you are unlikely to get bored! 

The EE KDF9 Algol manual is available in PDF and DjVu formats at: 

http: / /www. f indlavw. plus . com/KDF9/Documents/EE%2 0KDF9%2 0Alqol%2 0Manual. pdf 

and 

http://www.findlavw.plus.com/KDF9/Documents/EE%20KDF9%20Alqol%20Manual.divu 

A selection of Algol programs can be found in the directory Testing/Algol. 

I provide some shell commands, in the Testing directory, to make it a little easier to compile and run using 
Walgol. These commands take Algol 60 programs from text files named with the ‘ . a60’ suffix. The suffix is optional in 
a name given as parameter to the whet and lap commands: if supplied, it must be correct; if omitted, it is 
automatically restored. 

YOU DO NEED TO KNOW THE FOLLOWING: 

You are likely to encounter Walgol compilation and execution errors. They have identifying numbers, tabulated 
separately for Translator and Controller, in the file ‘Documents/Walgol Error Numbers.pdf’. 

A compilation listing is produced only if the response to the compiler’s ‘OUT; ’ prompt is an OUT 8 stream number 
(reply ‘10 . | ’ or ‘30 . | ’), rather than ‘N. |'. Stream 10 is directed to TP0; stream 30 goes to LP0. You may find that 
the listing disappoints: the source code is not included; instead the compiler outputs a table relating source line numbers 
to object code syllable addresses. 

When the Algol object program starts, it prompts ‘STREAM; ’ for the number of the OUT 8 spooled output stream to 
be used; again, reply ‘10. | ’ or ‘3 0 . | ’. This should be the same as the stream number specified in the source program. 

• The whet command compiles and executes a Whetstone Algol program; e.g.: 

./whet my_prog 

compiles and executes Testing/Algol/my_prog. a60, with the compiler in fast mode; alternative modes 
are as given, above, for the nine command. If you want to specify a mode for the execution of the object 
program by the Whetstone Controller, different from that used by the Whetstone Translator, then you need to set 
up an options file, settings_2 . txt. 

The tracing verbosity can specified by a fourth parameter, as for the nine command. For example: 

./whet my_prog t hps 

runs my_prog in trace mode, the tracing verbosity being reduced by omitting the histogram, peripheral I/O 
trace and signature. 

A Walgol source program and its (stream 20) data are both read from TR0, so it is convenient to include the program 
and its data in the same text file (my_prog. a60, in the given example). Alternatively, only the program need be held 
in that file, with its data in files TROa, TROb, etc., using the facility for attaching TR0 at run-time to a succession of 
files. The whet command sets up the FW0 file for the Whetstone system so that you do not need to type in any 
responses to Flexowriter prompts. If the given replies are unsuitable, change the data in: 

Testing/FW0_for_Whetstone. 

If either the TP0 or the LP0 file is found to be non-empty at the end of a run, it is displayed on the terminal. 

BUT YOU PROBABLY DON’T NEED TO KNOW THIS: 

• The lap (‘link Algol program’) command is used by whet to copy a data file into TR0. You can invoke it 
directly to supply a data file in TR0 for a run of ee9 that you call yourself. For example, the following is 
somewhat like the latter example of the . /whet command: 

./lap my_prog 
./dow t hps 

AND YOU PROBABLY DON’T NEED TO KNOW THIS EITHER: 

• The dow (‘do Whetstone’) command conveniently abbreviates a call on ee9 to execute the Whetstone system. 
For example, the following is somewhat like the latter example of the . /dow command: 

./ee9 -sp -dt -mhps +Binary/KMW0201—UPU 


2 

© 2018 William Findlay, kdf 9@f indlayw.plus . com 

This document is licensed under a Creative Commons Attribution 3.0 License : http://creativecommons.Org/licenses/by-nc-sa/3.0/ 






Grooving with Kalgol (the Kidsgrove Algol 60 system) 

The Kidsgrove Algol system is incomplete and known to be buggy. Some of its modules are missing and have been 
replaced with newly-written substitutes. The Kidsgrove compiler expects its input to be in Algol Basic Symbols, as 
provided by the EE POST and PROMPT systems. These have to be generated from the plain source code nowadays. 

The object program is generated in Usercode, which has to be assembled. For all these reasons, compiling and running 
an Algol program using the Kidsgrove system is complex and somewhat flakey. Nevertheless, it is instructive to do so, 
and worth the effort. 

I provide a shell command, kids, in the Testing directory, to make it easier to compile and run a Kidsgrove Algol 
program. The kids command takes two mandatory parameters, the Algol program name, and the name of any data file 
to be supplied on paper tape, e.g.: 

./kids QR QR_data t hps 
./kids WHETSTONE - 

Any additional parameters are taken to be mode and miscellany parameters for execution of the object program 

Directing Director (the EE Multiprogramming OS) 

EE implementation documentation describing the structure and functioning of Director is available at: 
http://sw.ccs.bcs.orq/KDF9/directorManuals/manuals.htm 

• I provide a shell command, tsd, in the Testing directory, to make it a little easier to run the EE Time Sharing Director. 
The tsd command takes only the optional diagnostic mode flags, e.g.: 

./tsd t hrs 

runs the Time Sharing Director in trace mode, without histogram, retrotrace or signature. 

The tsd command sets up the FWO file for Director, so that you do not need to type in any responses to prompts 
during its initialization phase. If the given replies are unsuitable, change the data in Testing/FW0_f or_Director. 
Before attempting to run Director, if you have not already run the self-test procedure, be sure to run the command: 

./nine_test RLT RLT_data 
or the equivalent shell command file: 

. /rlt 

to make sure all the magnetic tape decks have properly-labelled tapes to mount. The provided Director FWO file requests 
the loading of a binary program from TR1. If TR1 has not been linked in advance to a call tape for such a program, the 
run will fail. Instructions for using the Flexowriter to issue commands to Director are given in the Users’ Guide. 

• I provide a shell command, tsdnine, in the Testing directory, to make it easier to run a problem program under 
Director. The tsdnine command takes two mandatory parameters, the program name and the name of its data file, 
e.g.: 

./tsdnine LEECH Leech_data9 
./tsdnine DIVA - 

Any additional parameters are taken to be parameters for the tsd command, which tsdnine calls to run Director, 
tsdnine sets up a call tape for you automatically. 

• I provide a shell command, tsdwhet, in the Testing directory, to make it easier to compile and run a Whetstone 
Algol program under Director. The tsdwhet command takes one mandatory parameter, the Algol program name, e.g.: 

./tsdwhet WHETSTONE 

Any additional parameters are taken to be parameters for the tsd command, which tsdwhet calls to run Director, 
tsdwhet sets up a call tape for the Whetstone system automatically. 

YOU PROBABLY DON’T NEED TO KNOW THIS: 

• The tsd command conveniently abbreviates a call on ee9 to execute the Time Sharing Director. For example, 
the following is somewhat like the example of the . / tsd command: 

./ee9 -tb -dt -hrs +Binary/KKT40E007UPU 
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Building your own version of ee9 

The Build directory contains a command tile called mk9, which is used to build ee9 binaries. mk9 takes optional 
parameters that determine the build flags to be used for the compilation. These flags can easily be amended if you find 
that they are unsuitable for your development environment: see the ink9 file itself. The result of all compilations is left 
in in Testing. 

The first parameter of mk9 should be one of the following: 

ee9: make an optimised binary, with no optional compilation warnings, 

but with a high level of runtime checking enabled (default) 

warn: make an unoptimised binary, with many optional compilation warnings 

kal3: compile Build/kal3_source/kal3 . c/ 

kdf 9: compile Build/kal3_source/kdf 9 .c/ 

a2b: compile Source/a2b. adb 

a_block: compile Source/a_block. adb 

all: call mk9 successively with the tidy, kal3, kdf 9, a2b, a_block, and ee9 parameters 

tidy: establish a standard environment in the Testing directory, using the Build/ tidy command 

zip: create a compressed zip archive of emulation, named <distribution> . zip 

distro: call mk9 with the all parameter, and use Build/pk9 to create a ‘zip’ of the emulation directory; 

the binaries included in the distribution were created using the distro parameter. 

Note that optimised builds of ee9 run about 4 times faster than unoptimised builds! 

The second, distribution , parameter is given only if a build type is the first parameter, and is one of the following: 

UNIX,Unix,unix,LINUX,Linux, linux, macOS. Macintosh,Mac,OSX: 

Build a binary for macOS, Linux, or other POSIX system that supports ANSI-terminal escape sequences 
and has /dev/tty as the interactive terminal. macOS is the default, so, e.g.: 

./mk9 ee9 
has the same effect as: 

./mk9 ee9 macOS 

WINDOWS,Windows,or windows: 

Build a binary for Microsoft Windows, e.g.: 

./mk9 ee9 Windows 

The compilation listing is left in a file named Build/komlog. ada; it should be free of any compilation warning 
messages. It starts with a header that identifies the ee9 version, mk9 build type, and compilation options used. 

If you have difficulty in compiling ee9 warning-free, please let me know, as it may indicate a portability defect. 
However, if the problem is only that the gnatmake command rejects a parameter of the form -qnatvisomething or the 
form -gnaty something, it is safe to delete that whole parameter from the listed options within mk9, as it only controls 
optional warning messages, and they often differ between GNAT releases. 

N.B. See MISCELLANEOUS OS ISSUES in the README file for information about getting an Ada 2012 compiler, and 
other system components, needed to compile ee9. 

Packaging a version of ee9 

The Build directory contains a command file called pk9, which is used by mk9 to package up a version of ee9 as a 
zip archive file. The only, optional, parameter is the distribution type, as used by mk9. It can be used on its own to make 
zip archives of existing versions of ee9. pk9 in turn calls the tidy command to clear out work files in Build, truncate 
device files in Testing, and set many file permissions appropriately. 

N.B. The PowerPC target is no longer supported by mk9. Raspberry Pi binaries are now created in the same way as all 
other UNIX/Linux targets, subject to the availability of an Ada 2012 compiler. One such is available in the Debian 
Stretch release of Raspbian. 
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Utilising some utilities 

A number of Ada programs and shell command files are in the Testing directory for ease of use (the Ada source code 
is in the Source directory). Instructions for the most important of them follow. 

call_tape: output a program call tape in KDF9 paper tape code; take the medium ('D\ ‘M’ or ‘P’), the 'program 
reference number’ and ‘title’ from successive lines of standard input, and write the result to standard output. 

a2b: read data from standard input in a stated code and write it to standard output in another form. Conversions are 
available from raw bytes to paper tape code, between paper tape code and Latin-1, and from paper tape code to octal in 
half/word format with optional Q-store format and syllable format. The command takes the form: 

a2b { -r2p I -L2p I -p2LI-p2o} 

Exactly one flag parameter must be given; it is actually case-insensitive. The effect is as follows: 

-r2p Take the input to be ‘raw’ bytes, perhaps representing KDF9 syllables; read groups of 6 to 

form a 48-bit word; and output each such word as 8 KDF9 characters in paper tape code. 

-L2p Take the input to be 8-bit characters in Latin-1 code, transcribe them individually to KDF9 

characters in paper tape code. 

-p2L Take the input to be KDF9 characters in paper tape code, and transcribe them individually to 

8-bit characters in Latin-1 code. 

-p2o Take the input to be KDF9 characters in paper tape code, read groups of 8 to form a 48-bit 

word; output each such word in octal half/word, Q-store, syllable and character formats; 
report parity errors and incomplete words. 

tsdnine: simplify running problem programs under the Timesharing Director. The rlt shell command file is first run 
by tsdnine, with its usual data files, to ensure that the MT? files are set up for Director use. tsdnine then takes its 
first parameter to be the name of a Usercode program in the Assembly directory, assembles it using ucc, creates an A 
block for it using a_block, concatenates this with the output from ucc, and any given data file, and saves the result in 
TR1. It then invokes Director using the tsd command. Once Director has booted, a FLEX interrupt ( A C) makes it load 
and run the program from TR1 (the load command has been added to FW0_f or_Director). 
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